---
description: "Reference for Nitric's v0 JVM library - Create APIs with the Nitric JVM SDK"
---

# JVM - api()

Creates a new HTTP API.

<Tabs syncKey="jvm-lang">

<TabItem label="Java">

```java
import io.nitric.Nitric;

public class Application {
  public static void main(String[] args) {
    var api = Nitric.INSTANCE.api("public");

    Nitric.INSTANCE.run();
  }
}
```

</TabItem>

<TabItem label="Kotlin">

```kotlin
import io.nitric.Nitric

fun main() {
  val api = Nitric.api("public")

  Nitric.run()
}
```

</TabItem>

</Tabs>

## Parameters

<Properties>
  <Property name="name" required type="string">
    The unique name of this API within the app. Subsequent calls to `api` with
    the same name will return the same object.
  </Property>
  <Property name="options" type="ApiOptions">
    Additional options when creating the API.
    <Properties nested>
      <Property name="basePath" type="String">
        Base path for all routes in the API.
      </Property>
      <Property name="middleware" type="HttpMiddleware or List<HttpMiddleware>">
        Middleware to apply to all routes and methods of the API.
      </Property>
      <Property
        name="securityDefinitions"
        type="Map<String, SecurityDefinition>"
      >
        Security definitions defined by this API.
      </Property>
      <Property name="security" type="Map<String, List<String>>">
        Security rules to apply with scopes to the entire API. Keys must match a
        **securityDefinition**.
      </Property>
    </Properties>
  </Property>
</Properties>

### JWTSecurityDefinition Parameters

<Properties>
  <Property name="issuer" required type="String">
    the issuer for the JWT tokens e.g.{' '}
    <code>https://account.region.auth0.com</code>
  </Property>
  <Property name="audiences" required type="List<String>">
    the <code>aud</code> that will be applied to JWT tokens from the issuer.
  </Property>
</Properties>

### Notes

The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers or Auth, across an entire API from a single place.

## Examples

### Create an API

<Tabs syncKey="jvm-lang">

<TabItem label="Java">

```java
import io.nitric.Nitric;

public class Application {
  public static void main(String[] args) {
    var api = Nitric.INSTANCE.api("public");

    Nitric.INSTANCE.run();
  }
}
```

</TabItem>

<TabItem label="Kotlin">

```kotlin
import io.nitric.Nitric

fun main() {
  val api = Nitric.api("public")

  Nitric.run()
}
```

</TabItem>

</Tabs>

### Create an API with universal middleware

<Tabs syncKey="jvm-lang">

<TabItem label="Java">

```java
import io.nitric.Nitric;
import io.nitric.faas.v0.Handler;
import io.nitric.faas.v0.HttpContext;
import io.nitric.resources.ApiOptions;

public class Application {
  static HttpContext authMiddleware(HttpContext ctx, Handler<HttpContext> next) {
    // perform auth validation
    return next.invoke(ctx);
  }

  public static void main(String[] args) {
    var apiOpts = new ApiOptions.Builder().middleware(Application::authMiddleware).build();

    var api = Nitric.INSTANCE.api("public", apiOpts);

    Nitric.INSTANCE.run();
  }
}
```

</TabItem>

<TabItem label="Kotlin">

```kotlin
import io.nitric.Nitric
import io.nitric.faas.v0.HttpContext
import io.nitric.faas.v0.Middleware
import io.nitric.resources.ApiOptions

val authMiddleware = Middleware<HttpContext> { ctx, next ->
  // perform auth validation
  return@Middleware next(ctx)
}

fun main() {
  val api = Nitric.api("public", ApiOptions(middleware = authMiddleware))

  Nitric.run()
}
```

</TabItem>

</Tabs>

### Notes

Middleware functions are supplied a `HttpContext` object and a `next()` function which calls the next middleware in the chain.

### Create an API with a base path

If you need to put all the routes in your api below a shared base path, you can do that with the `basePath` option. In this example we ensure all routes start with `/api/v1/` before the route specific path.

<Tabs syncKey="jvm-lang">

<TabItem label="Java">

```java
import io.nitric.Nitric;
import io.nitric.resources.ApiOptions;

public class Application {
  public static void main(String[] args) {
    var apiOpts = new ApiOptions.Builder().basePath("/api/v1").build();

    var api = Nitric.INSTANCE.api("private", apiOpts);

    Nitric.INSTANCE.run();
  }
}
```

</TabItem>

<TabItem label="Kotlin">

```kotlin
import io.nitric.Nitric
import io.nitric.faas.v0.HttpContext
import io.nitric.faas.v0.Middleware
import io.nitric.resources.ApiOptions

val authMiddleware = Middleware<HttpContext> { ctx, next ->
  // perform auth validation
  return@Middleware next(ctx)
}

fun main() {
  val api = Nitric.api("public", ApiOptions(basePath = "/api/v1"))

  Nitric.run()
}
```

</TabItem>

</Tabs>

### Apply JWT authentication to an API

<Tabs syncKey="jvm-lang">

<TabItem label="Java">

```java
import io.nitric.Nitric;
import io.nitric.resources.ApiOptions;
import io.nitric.resources.JwtSecurityDefinition;

import java.util.List;
import java.util.Map;

public class Application {
  public static void main(String[] args) {
    var secureApiOpts = new ApiOptions.Builder()
      // security requirements for your API are defined here
      .securityDefinitions(Map.of(
        // define a security definition called 'user'
        "user", new JwtSecurityDefinition(
          "https://example-issuer.com",
          List.of("YOUR-AUDIENCES")
        )
      )).security(Map.of(
        // apply the 'user' security definition to the whole API with the scopes required.
        // in this case users will require the 'products:read' scope to access the API
        "user", List.of("products:read")
      )).build();

    var secureApi = Nitric.INSTANCE.api("secure", secureApiOpts);

    Nitric.INSTANCE.run();
  }
}
```

</TabItem>

<TabItem label="Kotlin">

```kotlin
import io.nitric.Nitric
import io.nitric.resources.ApiOptions
import io.nitric.resources.JwtSecurityDefinition

fun main() {
  val secureApi = Nitric.api("secure", ApiOptions(
    // security requirements for your API are defined here
    securityDefinitions = mapOf(
      // define a security definition called 'user'
      "user" to JwtSecurityDefinition(
          issuer = "https://example-issuer.com",
          audiences = listOf("YOUR-AUDIENCeS")
      )
    ),
    security = mapOf(
      // apply the 'user' security definition to the whole API with the scopes required.
      // in this case users will require the 'products:read' scope to access the API
      "user" to listOf("products:read")
    ))
  )

  Nitric.run()
}
```

</TabItem>

</Tabs>
